home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / telecomm / fnorddel / fn132man.zoo / chapter.07 < prev    next >
Text File  |  1991-09-02  |  6KB  |  152 lines
  1.  
  2.  
  3. Chapter 7:  Events                                                        93
  4.  
  5.  
  6.  
  7.  
  8. 7  Events
  9.  
  10.  
  11.    Events are a  highly generalised way of  making your Fnordadel do  things
  12. that  it  otherwise  couldn't,  like  interface  with  networks  other  than
  13. Citadel, run  utility programs regularly, et  cetera.  The mechanism  allows
  14. unlimited flexibility with minimal  useless baggage; if we had to  build all
  15. these neat extra things  into Fnordadel itself, it would be  the programming
  16. equivalent of Monty Python's ``Mr.  Creosote''.
  17.  
  18.    There are three general types of events.
  19.  
  20.   o __Timeout events__  cause Fnordadel  to exit to  its calling program  (a
  21.     shell, if you  want to do anything useful) at a specified day  and time.
  22.     The BBS  will be polite  enough to wait for  any current online user  to
  23.     terminate before exiting.
  24.  
  25.   o __Preemptive  events__ are  like timeout  events  except that  Fnordadel
  26.     won't be the  least bit polite; it will immediately boot anybody  who is
  27.     logged in.
  28.  
  29.   o __Network  events__  invoke  the  built-in  networker,  to  do  standard
  30.     Citadel networking.   Please see Chapter 8 [Networking], page 96,  for a
  31.     nauseatingly-detailed description of  networking.  These kind  of events
  32.     will rudely  boot any online user,  as with the  preemptive type.   Note
  33.     that during  a network event, the  system will be effectively closed  to
  34.     normal user traffic---it will blurt out a  terse message if it discovers
  35.     that a caller is not a Citadel net node, and drop carrier on him/her.
  36.  
  37.  
  38. 7.1  Events In General
  39.  
  40.    Events are  set up in  `ctdlcnfg.sys', as  you'd expect.   Each event  is
  41. defined separately, and the format of the definition is:
  42.  
  43.       #event <type> [days] <time> <duration> <name> <flags>
  44.  
  45. where the fields mean:
  46.  
  47. <type>     One of `timeout', `preemptive' or `network'.
  48.  
  49. [days]     This is  optional.  If  there, it gives  the days that the  event
  50.            will  happen.   This  field  is either  `all',  meaning that  the
  51.            event  happens every day,  or  any combination  of `Mon',  `Tue',
  52.            `Wed', `Thu', `Fri', `Sat', or `Sun'---separated by  commas.  For
  53.            example,  if  you wanted  an  event for  Monday,  Wednesday,  and
  54.            Saturday, you would use a days field of `Mon,Wed,Sat'.
  55.  
  56. <time>     When the  event is scheduled to  go off (in 24-hour  time---e.g.,
  57.            3:00pm is `15:00').
  58.  
  59. <duration>
  60.            How  long  the event  is  supposed  to  last,  in minutes.     If
  61.            Fnordadel is  brought up after the start  of an event but  before
  62.            the event  is supposed  to be  over, it will  immediately do  the
  63.            event.
  64.  
  65.  
  66.  
  67. Chapter 7:  Events                                                        94
  68.  
  69.  
  70.  
  71.  
  72. <name>     A meaningful (to you)  name for the event (up to  19 alphanumeric
  73.            characters, no spaces.)
  74.  
  75. <flags>    Depends  on the  type  of  event.    For timeout  and  preemptive
  76.            events, it  is the condition code  to be returned to the  calling
  77.            program;  remember  not to  use `0'  through  `3', as  these  are
  78.            reserved  for  Fnordadel's  own purposes.     (See  `citadel.man'
  79.            for  their specific  meanings.)    For  network  events,  <flags>
  80.            represents the  number of  the specific  net to  be used.    (See
  81.            Section 8.1.3.1 [Network events], page 101, for more details.)
  82.  
  83.    Here are a couple of examples:
  84.  
  85.       #event NETWORK all 2:30 30 ld-net 1
  86.  
  87.    This sets up a network  event to run every night at 2:30 AM,  lasting for
  88. 30 minutes.  The event is called `ld-net', and will use network #1.
  89.  
  90.       #event TIMEOUT Mon,Wed,Fri 6:00 0 uucp-net 10
  91.  
  92.    This one sets up a  timeout event for 6:00 AM on Mondays,  Wednesdays and
  93. Fridays.  The event  is called `uucp-net', and exits to the shell  with code
  94. 10.  (The shell,  presumably, knows what to do when it gets a  10 back---see
  95. Section 11.2  [Running from  a Shell],  page 145.)    Since the  event is  a
  96. timeout and not preemptive, if a user is logged in  at 6:00, the system will
  97. wait until he/she terminates before exiting to the shell.
  98.  
  99.    You may  have  any number  of events  defined in  `ctdlcnfg.sys',  though
  100. there are some practical  limits---too many events and your system  won't be
  101. up long enough for a user to sign on.
  102.  
  103.  
  104.  
  105. 7.2  Some Notes on Events
  106.  
  107.   o See  Chapter  11  [Shells  vs.     the  Desktop],  page  143,  for  some
  108.     ideas  of what  to  use  all this  event  stuff for.    But  we'll  tell
  109.     you  now:  If  you're running  from the  desktop, you  can't really  use
  110.     timeout/preemptive  events, because  the desktop  has  no mechanism  for
  111.     dealing with codes returned by programs.
  112.  
  113.   o If  you set up  a timeout  event, followed  soon after  by a  preemptive
  114.     event,  and a  user logs  stays logged in  through the  duration of  the
  115.     timeout and into the preemptive, silly things will probably happen.
  116.  
  117.   o If  the event  is a  timeout or  preemptive event,  you'd probably  want
  118.     to use  a <duration> of  `0', to prevent  the situation where  Fnordadel
  119.     exits,  the shell does whatever  it does, the  shell finishes, and  then
  120.     reruns Fnordadel,  all before  <duration> has expired---Fnordadel  would
  121.     then exit all over again.
  122.  
  123.   o An event causes  Fnordadel to exit completely; this is different  from a
  124.     door, which causes Fnordadel to act as a  shell and run another program,
  125.     while still remaining in  memory.  See Chapter 9 [Doors], page  126, for
  126.     information on doors.
  127.  
  128.  
  129.  
  130. Chapter 7:  Events                                                        95
  131.  
  132.  
  133.  
  134.  
  135. 7.3  Timeouts
  136.  
  137.    An additional form of event  is the specialised variable timeout.   (This
  138. should not be  confused with an #event of type  #timeout.)  If you  have the
  139. variable #timeout defined as `1' in `ctdlcnfg.sys',  Fnordadel will look for
  140. another variable called  #hourout.  The system  will set up a  timeout event
  141. for #hourout  hours after the system  comes up, and  will exit to the  shell
  142. with a condition code of `1'.  Here's an example:
  143.  
  144.       #define timeout 1
  145.       #define hourout 8
  146.  
  147.    This will, in effect,  cause Fnordadel to take itself down every  8 hours
  148. (because the counter is reset  every time the is brought up.)   This feature
  149. is designed  for doing  things like  regular backups controlled  by a  shell
  150. script.
  151.  
  152.